Inside Macintosh: QuickTime Components
Sequence grabber components store their configuration information in Movie Toolbox user data items (see the chapter "Movie Toolbox" in Inside Macintosh: QuickTime for more information about user data items). This configuration information includes settings for each of the channels used by the sequence grabber. Because your panel component configures sequence grabber channels, your panel component is responsible for creating and formatting the contents of its user data items. The sequence grabber component calls your component whenever it wants to retrieve these settings. The sequence grabber may also use previously stored settings to restore your panel's settings. This section discusses the functions that allow the sequence grabber to work with your panel's settings.
The sequence grabber calls your SGPanelGetSettings function in order to retrieve your panel's current settings. The sequence grabber uses your SGPanelSetSettings function to restore those settings to some previous values.
Sequence grabber components call your component's SGPanelGetSettings function in order to retrieve your panel's current settings.
pascal ComponentResult SGPanelGetSettings
(SeqGrabComponent s,
SGChannel c, UserData *ud,
long flags);
A sequence grabber component calls your SGPanelGetSettings function in order to obtain a copy of your panel's current settings. The sequence grabber stores these settings for you and may use them to restore your panel's settings by calling your SGPanelSetSettings function (described next). Your component should store whatever values are necessary to properly configure your associated channel component. For example, Apple's video compression panel component saves such values as video compressor component type, compression quality, key frame rate, and frame rate values.
These settings may be stored as part of a larger sequence grabber configuration and may be stored for a long period of time. Therefore, you should not store values that may change without your knowledge (such as component ID or connection values).
You are free to format the data in the user data item in any way you desire. Make sure you can retrieve the settings information from the user data item when your SGPanelGetSettings function is called. You may choose to format the data in such a way that other components can parse it easily, thus allowing your component to operate with other panel components.
You create a new user data item by calling the Movie Toolbox's NewUserData function (see the chapter "Movie Toolbox" in Inside Macintosh: QuickTime for more information about this function). You may then use other Movie Toolbox functions to manipulate the user data item.
Sequence grabber components call your component's SGPanelSetSettings function in order to restore your panel's current settings.
pascal ComponentResult SGPanelSetSettings
(SeqGrabComponent s,
SGChannel c, UserData ud,
long flags);
A sequence grabber component calls your SGPanelSetSettings function in order to restore your panel's settings. The sequence grabber may call this function when the user cancels the settings dialog box.
Your component originally creates the settings information when the sequence grabber calls your SGPanelGetSettings function (described in the previous section). The sequence grabber passes this configuration information back to you in the ud parameter to this function. Your component should parse the configuration information and use it to establish your panel's current settings.
Note that your component may not be able to accommodate the original settings. For example, because the settings may have been stored for some time, the hardware environment may not be able to support the values in the settings. You should try to make your new settings match the original settings as closely as possible. If you cannot get close enough, return an appropriate sequence grabber or sequence grabber channel result code.
You may use Movie Toolbox functions to manipulate the user data item (see the chapter "Movie Toolbox" in Inside Macintosh: QuickTime for more information about functions that work with user data items).